/*
CpGears v1.0

Copyright (c) 2010 Yves Riel http://www.flash-factor.com

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/

package cpgears.movie {
	import cpgears.helpers.Version;
	import cpgears.movie.controls.IMovieControls;
	import cpgears.movie.MetaData;
	import cpgears.movie.slide.ISlide;
	import cpgears.movie.widget.IWidget;
	import flash.display.MovieClip;
	import flash.events.IEventDispatcher;
	
	/**
	 * Interface representing the information of a Captivate movie.
	 * 
	 * @author Whyves
	 */
	public interface IMovie extends IEventDispatcher {
		/**
		 * The width of the Captivate movie excluding the playbar and TOC if applicable.
		 */
		function get contentWidth():Number;

		/**
		 * The height of the Captivate movie excluding the playbar and TOC if applicable.
		 */
		function get contentHeight():Number;
		
		/**
		 * The top left corner Y position of the Captivate movie.
		 */
		function get contentTop():Number;

		/**
		 * The top left corner X position of the Captivate movie.
		 */
		function get contentLeft():Number;
		
		/**
		 * Information about the widget in the Captivate context.
		 */
		function get widget():IWidget;

		/**
		 * The slide containing the widget.
		 */
		function get slide():ISlide;
		
		/**
		 * The version number for Captivate
		 */
		function get captivateVersion():Version;
		
		/**
		 * Returns the value of a Captivate variable.
		 * 
		 * @param	variableName The name of the Captivate variable to retrieve.
		 * @return	The value of the variable, <code>null</code> otherwise.
		 */
		function getCpVariable(variableName:String):*;

		/**
		 * Sets the value of a specific Captivate variable.
		 * 
		 * @param	variableName The name of the Captivate variable to set.
		 * @param	value The value of the variable.
		 */
		function setCpVariable(variableName:String, value:*):void;
		
		/**
		 * Causes the movie to jump to the specified slide.
		 * 
		 * <p>The slide number are zero based meaning that the first slide is
		 * slide 0.</p>
		 * 
		 * @param	SlideNumber The slide number to jump to.
		 */
		function gotoSlide(SlideNumber:Number):void;
		
		/**
		 * Returns if the movie has a playbar.
		 * 
		 * @return <code>true</code> if the movie has a playbar, <code>false</code> otherwise.
		 */
		function hasPlaybar():Boolean;
		
		/**
		 * Returns the metadata associated to the movie.
		 */
		function get metadata():MetaData;
		
		/**
		 * Returns information about the user's system.
		 */
		function get systemData():SystemData;
		
		/**
		 * In a text, replaces all instances of a Captivate variable by their associated values.
		 * 
		 * <p>Scans a text and replaces all occurences of a Captivate variable (enclosed in %%) by its associated value. E.g.
		 * The string 'Captivate version: %%CaptivateVersion%%.' would become: 'Captivate version: 5.0.0.'</p>
		 * 
		 * @param	text The text to convert which contains the Captivate variables.
		 * @return The text where all Captivable variables have been replaced by their values.
		 */
		function replaceVariables(text:String):String;
		
		/**
		 * Monitors a movie variable for changes.
		 * 
		 * @param	variableName The name of the variable to monitor.
		 */
		function monitorVariable(variableName:String):void;
		
		/**
		 * Determines if the movie is in preview mode inside Captivate.
		 * 
		 * @return <code>true</code> if in preview mode, <code>false</code> otherwise.
		 */
		function isPreview():Boolean;
		
		/**
		 * Returns the movie controls.
		 */
		function get controls():IMovieControls;
				
		/**
		 *  Returns the presentation main movie (CaptivateMainTimeline).
		 */
		function get handle():MovieClip;
	}
}